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1.0 INTRODUCTION 



The CYBILIO package (CYBILIO) is a collection of procedures and data 
types which provide an Input/Output system that interfaces a CYBIL program 
to the NOS & NOS/BE I/O system. 



c 



^^•y 



1.1 APPLICABLE DOCUMENTS 

60455280 CYBIL Reference Manual 

60457280 Language Specification for CDC CYBER IMPLEMENTATION LANGUAGE 

60457250 SES User's Handbook 

60459660 NOS Version 2 Reference Manual (Volume 1) 

60459670 NOS Version 2 Reference Manual (Volume 2) 

60459680 NOS Version 2 Reference Manual (Volume 3) 

60459690 NOS Version 2 Reference Manual (Volume 4) 

60450100 NOS Version 1 Modify Reference Manual 

60493800 NOS/BE Version 1 Reference Manual 

60494100 NOS/BE Version 1 System Programmer's Reference Manual 

60499900 Update Version 1 Reference Manual 
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1.2 FILE TYPES 

CYBILIO deals with a (small) number of distinct types of files. The 
properties of the various file types are described in the subsections 
which follow. 



1.2.1 BINARY FILES 



Binary files have only sequential access. Data appears on such files 
in the order in which it was written, and can only be read in that same 
order. These files may be positioned at the beginning or end of 
information. Note that positioning at the beginning and then writing a 
binary file implies that all data which was previously on the file is 
lost. 

Binary files may be structured using record/file marks, and detection 
of the structure is possible. 



1.2.2 DIRECT FILES 



Direct files are like binary files except that data may be transferred 
to/from them at "random addresses" known as keys . Note that writing (from 
the beginning of) a direct file does not necessarily imply that existing 
data (which follows the data being written) will be lost (c.f., binary 
files). 

In addition to the positioning facilities provided for binary files, 
direct files may be positioned via a key to any location. 



1.2.3 LEGIBLE FILES 



Legible files are sequentially accessed and are assumed to contain 
character data in NOS 6/12 or in NOS/BE 8/12 representation. Legible I/O 
procedures provide for the conversion between the external (on the file) 
data format and the internal format (CYBIL strings). The basic entity on 
a legible file is a line which can be transferred to/from the file in 
whole or in part. In addition, there is a facility to tab to a specified 
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1.2.3 LEGIBLE FILES 



column in an output line. 

The same structuring and positioning facilities provided for binary 
files are also available for legible files. 






1.2.4 PRINT FILES 



Print files are legible files which have additional facilities for 
(vertical) format control. It is possible to limit the number of lines on 
a page, insert a given number of empty lines, overprint lines, position 
the next line at a specified line number or at the top of the next page. 
Several procedures are provided to change and interrogate certain items of 
control information for print files. 

The user may associate with each print file, a procedure to be called 
when a "page overflow condition" occurs for that file. Such a procedure 
can perform page heading (titling) and footing operations. 






o 



60460300 02 



CYBER IMPLEMENTATION LANGUAGE 
CYBIL I/O Reference Manual 



1-4 

06/22/84 
REV: 2 



4 Y 






1.0 INTRODUCTION 

1.3 CYBILIO DATA TYPES 



1.3 CYBILIO DATA TYPES 



This section defines the CYBIL "types" required to interface to 
CYBILIO. 



TYPE file 



'CELL; 



This type is used when calling any of the CYBILIO procedures. A 
variable of this type is defined when passed to one of the file open 
procedures, and remains defined until the corresponding close procedure is 
called. 



TYPE file_status = (new#, old#); 

This type is used when opening a file to designate whether the file 
already exists or needs to be "created". 



TYPE filejnode = (input#, output*, concurrent*); 

This type is used when opening a file to designate the "direction" of 
data transfers. 



TYPE file_position = (first*, asis*, last//, null#); 

This type is used when opening a file to designate where the file 
should be initially positioned (at its beginning, where ever it happens to 
be, at its end, or where ever it happens to be). Please note that usage 
of asis* or null* will yield the same result. 



„y 



CONST return* - last#; 
TYPE file_disposition = first* .. return*; 
{ i.e., (first*, asis*, return*) } 

This type is used when closing a file to designate at what "position" 
(or with which "disposition") the file should be left (at its beginning, 
where ever it happens to be, or "return" it to the operating system). 
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TYPE file_encoding = (ascii64#, ascii612#, ascii#); 

This type is used to define the (external) character set for a legible 
or print file. The default on NOS, when the file is opened, is ascii612# 
which designates the NOS 6/12 character set. The default on NOS/BE is 
ascii#. The user can select the 6-bit display code character set 
designated by ascii64# , or the "8 out of 12 bit" ASCII character set 
designated by ascii#. 



TYPE filejnark = (data#, eor#, eof#, eoi#); 

This type is used to designate the file structure marks. A value of 
this type can be obtained for a file subsequent to a performing an input 
(read, get) request on the file. Thus, dataif means "no mark encountered"; 
eor# means "a (logical) End Of Record was encountered"; eof# means "a 
(logical) End Of File was encountered"; and eoi# means "the End of 
Information was encountered". 
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1.4 USING CYBILIO 



The identifiers for all CYBILIO procedures adhere to the following 
naming convention: 

60460300 02 



o 



1.4 USING CYBILIO 

1.4.1 SOURCE CODE INTERFACE TO CYBILIO ON NOS 

To interface to CYBILIO a CYBIL program module must include the 
relevant type and procedure declarations. These can be *CALLed from a 
MODIFY program library (PL). The name of this program library is CYBCCMN, 
which is accessible by including the CYBCCMN parameter in the SES.GENCOMP 
call or can be made local by SES.GETCCMN. The CYBILIO type declarations ^ ^ 
are on common deck PXIOTYP and each procedure declaration is on its own i j 
common deck (see the section on naming conventions and the individual ^ 

procedure descriptions to determine the common deck names). 



1.4.2 SOURCE CODE INTERFACE TO CYBILIO ON NOS/ BE 



To interface to CYBILIO a CYBIL program module must include the 
relevant type and procedure declarations. These can be *CALLed from an 
UPDATE program library (PL). The name of this program library is CYBCCMN. 
The CYBILIO type declarations are on common deck PXIOTYP and each 
procedure declaration is on its own common deck (see the section on naming 
conventions and the individual procedure descriptions to determine the 
common deck names). 



1.4.3 OBJECT CODE INTERFACE TO CYBILIO 



Before a program (which uses CYBILIO) can be executed, it must be 
linked with the CYBILIO object modules which are located on The CYBIL-CC 
run-time library, which is accessible by including the CYBCLIB parameter 
on the loader directives. On NOS this could be via the SES.LINK170 or on 
NOS & NOS/BE by having CYBCLIB as a local file at program load time. 



1.4.4 NAMING CONVENTIONS 
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1.4.4 NAMING CONVENTIONS 



- all BINARY file procedure identifiers begin with bi# 

- all DIRECT file procedure identifiers begin with di# 

- all LEGIBLE file procedures identifiers begin with lg# 

- all PRINT file procedure identifiers begin with pr# 

- identifiers for procedures which are applicable to all file types 
begin with f# 

The names of the common decks which contain the CYBILIO procedure 
declarations are derived by taking (up to) the first seven characters of 
the procedure name and changing the £ character in the procedure name to a 
Z for the common deck name. 

Note_: that all common decks required for a particular file type can be 
included with MODIFY's *CALLALL directive. For example, a program that 
uses legible and print files could bring in all the relevant declarations 
as follows : 

*CALL pxiotyp 
*CALLALL lgz 
*CALLALL prz 
*CALLALL fz 



1.4.5 FILE VARIABLE USAGE 

CYBILIO considers a variable of type file to be undefined until one of 
the open procedures has been called; and to become undefined once one of 
the close procedures has been called. The consequences of using an 
undefined file variable to call any CYBILIO procedure (except one of the 
open procedures) is unpredictable. 



1.4.6 FILE NAMES 



File names (which are passed as adaptable CYBIL strings to the open 
procedures) must be from one to seven alphanumeric characters (i.e., 
letters or digits). The open procedures will convert any lower case 
letters in a file name to the corresponding upper case letters. 
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1.4.7 FILE STRUCTURE CREATION / DETECTION 



CYBILIO supports both the creation and detection of file structuring 
"marks". There are two such marks : End Of (logical) Record; and End Of 
(logical) File. The End Of Information can only be implicitly created 
(i.e., the End Of Information follows the physically last item written on 
a file); but it can be explicitly detected. 

Note that detection of a file structure mark can only be meaningfully 
attempted after an input request on the file. 

When performing input operations on binary and direct files, it is 
possible to have an incomplete transfer . This can result from reading a 
file not created by CYBILIO, or not reading a file in a manner which 
mimics the way in which the file was written. In order to handle these 
incomplete transfers, a procedure is provided to return the last transfer 
length for a file. The value returned by this procedure is only 
meaningfull if the immediately preceding operation on the file was one of 
: bi#get, bi#put, di#get, di#getdir, lg#get, lg#getpart, lg#put, 
lg#putpart, lg#tab, or lg#weol. 



1.4.8 CIO BUFFER SIZE CONTROL 



The size of the CIO circular buffer can be selected for files used with 
CYBILIO by setting the INTEGER variable px#iobs to the desired size. The 
value of this variable is used by the file open procedures in order to 
create a CIO circular buffer with the designated size. The declaration 
for this variable is contained on common deck PXZIOBS. 






1.4.9 LONG STRING OF BLANK (SPACE) CHARACTERS 



CYBILIO needs a long (256) string of blank characters in order to 
efficiently perform the lg#tab and pr#tab operations. This string is made 
available to the user in the variable px#blnk . The declaration for this 
variable is located on common deck PXZBLNK. 
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2.0 I/O PROCEDURES 



2.1 BINARY FILES 

2.1.1 OPENING AND CLOSING BINARY FILES 

2.1 .1.1 BIROPEN - Open Binary File 

Opens binary_file as local file_name. 

{ PXIOTYP Contains CYBIL type declarations. } 

TYPE 

file = "cell, 

file_status = (new#, old#), 

file_mode = (input#, output//, concurrent#), 

file_encoding = (ascii64#, ascii612#, ascii#), 

file_mark = (data#, eor#, eof#, eoi//), 

file_position = (first//, asis#, last#, null#); 

CONST 

return# = last//; 

TYPE 

file_disposition = first// .. return//; 

{i.e. (first//, asis//, return//) } 

{ BIZOPEN Opens binary file as local file. } 

PROCEDURE [XREF] bi#open (VAR binary_file: file; 
file_name: string ( * ); 
status: file_status; 
mode: file_mode; 
position: f ile_position); 
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2.1.1.2 BI//CLOSE - Close Binary File 



2.1.1.2 Biy/CLOSE - Close Binary File 



Closes binary file. 



{ BIZCLOS Closes binary file. } 

PROCEDURE [XREF] bi#close (binary_f ile: file; 
disposition: file disposition); 
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2.1.2 POSITIONING BINARY FILES 

2.1.2.1 BI//FIRST - Position Binary File at BOI 

Positions binary_file at its beginning of information. 

{ BIZFIRS Positions binary file at its beginning of information. } 
PROCEDURE [XREF] bi#first (binary_f ile: file); 

2.1.2.2 BI//LAST - Position Binary File at EOI 

Positions binary_file at its end of information. 

{ BIZLAST Positions binary file at its end of information. } 
PROCEDURE [XREF] bi#last (binary file: file); 
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2.1.3 BINARY FILE STRUCTURE CREATION / DETECTION 

2.1.3.1 BI#WE0R - Write End Of Record on Binary File 

Writes an End Of Record mark on binary_file. 

{ BIZWEOR Writes and End of Record mark on binary file. } 
PROCEDURE [XREF] bi#weor (binary_f ile: file); 

2.1.3.2 BI#WE0F - Write End Of File on Binary File 

Writes an End Of File mark on blnary_file. 

{ BIZWEOF Writes an End of File mark on binary file. } 
PROCEDURE [XREF] bi#weof (binary_f ile: file); 

2.1.3.3 F#MARK - Check Structure Mark on File 

Returns the "file structure mark" last encountered on any_file. 

{ FZMARK Returns the file structure mark last encountered on file. } 

PROCEDURE [XREF] f#mark (any_file: file; 
VAR mark: file mark); 
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2.1.3.4 F#WORDS - Last Transfer Length on File 



2.1.3.4 F//WORDS - Last Transfer Length on File 



Returns the length of the last transfer to/from any file. 



{ FZWORDS Returns length of last transfer to/ from file. } 

PROCEDURE [XREF] f#words (any_file: file; 
VAR last transfer length: integer); 
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2.1.4 READING AND WRITING BINARY FILES 

Transfer of data to and from binary files is performed in groups of 
words (cells). Since the data transfer procedures for binary files (like 
all other programmer defined procedures in CYBIL) must have parameters of 
a specific type, and since we want to be able to transfer items of any 
data type to/from a binary file, the objects of transfer are passed to the 
procedures in two parts: address (usually via the #loc function); and 
length (usually via the #size function). CYBILIO has no way to insure 
that the address and length parameters refer to the same object, therefore 
be warned: "you're on your own" as far as checking parameter correctness 
is concerned. 



2.1.4.1 BI//PUT - Write to Binary File 



Writes length_of_source words (cells) beginning at the address 
specified by pointer to source to binary file. 



{ BIZPUT Writes specified information to binary file. } 

PROCEDURE [XREF] bi#put (binary_f ile: file; 
pointer_to_source: ~cell; 
length of source: integer); 



2.1.4.2 BI//GET - Read from Binary File 



Reads up to length_of_target words (cells) from binary_file to the 
address specified by pointer_to_target . Note that an "incomplete 
transfer" can result from this request (see the section on "File Structure 
Creation / Detection" for more information on this subject) . 



{ BIZGET Reads info from binary file to address specified. } 

PROCEDURE [XREF] bi#get (binary_f ile: file; 
pointer_to_target: ~cell; 
length_of_target : integer); 
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2.1.5 EXAMPLE - COPY BINARY FILE 



The following example illustrates the use of the binary file procedures 
to make a copy of a file (without knowing beforehand the structure or 
length of the file). 



MODULE copy ALIAS 'zpxmcop'; 

{ PXIOTYP Contains CYBIL type declarations. } 

TYPE 

file = "cell, 

file_status = (new#, old//), 

file_mode = (input#, output//, concurrent^, 

file_encoding = (ascii64#, ascii612#, ascii#), 

file_mark = (data#, eor#, eof#, eoi#), 

file_position = (first//, asis//, last#, null#); 

CONST 

return// = last//; 

TYPE 

file_disposition = first// .. return//; 

{ i.e. (first#, asis//, return//) } 

{ BIZOPEN Opens binary file as local file. } 

PROCEDURE [XREF] bi//open (VAR binary_f ile : file; 
file_name: string ( * ); 
status: file_status; 
mode: file_mode; 
position: file_position); 

{ BIZCLOS Closes binary file. } 

PROCEDURE [XREF] bi//close (binary_f ile: file; 
disposition: f ile_disposition); 

{ BIZGET Reads info from binary file to address specified. } 

PROCEDURE [XREF] bi#get (binary_f ile: file; 
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pointer_to__target: "cell; 
length_of_target: integer); 

{ BIZPUT Writes specified information to binary file. } 

PROCEDURE [XREF] bi#put (binary_file: file; 
pointer_to_source: A cell; 
length_of_source: integer); 

{ BIZWEOR Writes and End of Record mark on binary file. } 

PROCEDURE [XREF] bi#weor (binary_f ile : file); 
{ BIZWEOF Writes an End of File mark on binary file. } 

PROCEDURE [XREF] bi#weof (binary_f ile: file); 

{ FZMARK Returns the file structure mark last encountered on file. } 

PROCEDURE [XREF] f#mark (any_file: file; 
VAR mark : f ilejnark) ; 

{ FZWORDS Returns length of last transfer to/from file. } 

PROCEDURE [XREF] f#words (any_file: file; 
VAR last_transfer_length: integer); 

PROGRAM copy ALIAS 'zpxpcop'; 

CONST 

in_name = 'OLD', 
out_name = 'NEW' , 
buffer_length = 64; 

VAR 

in_file : file, 

out_file : file, 

buffer : ARRAY [1 .. buffer_length] of CELL, 

transfer_length : INTEGER, 

mark : file_mark; 

bi#open (in_file, injiame, old#, input* , first#); 
bi#open (out_file, out_name, new#, output#, first#); 
/main_loop/ 
WHILE TRUE DO 

bi#get (in_file, #L0C(buf f er) , #SIZE(buf fer)); 
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f#mark (in_file, mark); 

CASE mark OF 

=eoi#= 

EXIT /main_loop/; 
=eof#= 

bi#weof (out_file); 
=eor#= 

f#words (in_file, transf er_length) ; 
IF transfer_length > THEN 

bi#put (out_file, #LOC(buf f er) , transfer length); 
I FEND; ~ 

bi#weor (out_file); 
=data#= 

bi#put (out_flle, #LOC(buffer), iSIZE(buffer)); 
CASEND; 
WHILEND /main_loop/; 
bi#close (in_flle, first#); 
bi#close (out_file, first#); 

PROCEND copy; 

MODEND copy; 
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2.2 DIRECT FILES 

2.2.1 OPENING AND CLOSING DIRECT FILES 

2.2.1.1 DI#OPEN - Open Direct File 



Opens direct_file as local file_name. Note ; that a direct file cannot / — ^ 
be opened at position asis#. ^ J 

{ DIZOPEN Opens direct file as local file. } 

PROCEDURE [XREF] di#open (VAR direct_file: file; 
file_name: string ( * ); 
status: file_status; 

mode: file_mode; _ 

position: file position); ) 



2.2.1.2 DI#CL0SE - Close Direct File 



Closes direct file. 



' DIZCLOS Closes direct file. } 

PROCEDURE [XREF] di#close (direct_file: file; 
disposition: f ile_disposition); 
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2.2.2 POSITIONING DIRECT FILES 

2.2.2.1 DIffFIRST - Position Direct File at BOI 

Positions direct_file at its beginning of information. 

{ DIZFIRS Positions direct file at its beginning of information. } 
PROCEDURE [XREF] di#first (direct_f ile: file); 

2.2.2.2 DI//LAST - Position Direct File at EOI 

Positions direct_file at its end of information. 

{ DIZLAST Positions direct file at its End of Information. } 
PROCEDURE [XREF] di#last (direct_f ile: file); 

2.2.2.3 DISLOCATE - Position Direct File via Key 



Positions direct_file at the location specified by key. If key 
specifies a position outside the bounds of the file, then the program is 
in error. 



{ DIZLOCA Positions direct file at location specified. } 

PROCEDURE [XREF] di#locate (direct_file: file; 
key: integer); 
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2.2.3 DIRECT FILE STRUCTURE CREATION / DETECTION 

2.2.3.1 DI#WE0R - Write End Of Record on Direct File 

Writes an End Of Record mark on direct_file. 

{ DIZWEOR Writes an End of Record mark on direct file. } 
PROCEDURE [XREF] di#weor (direct_f ile: file); 

2.2.3.2 DI#WEOF - Write End Of File on Direct File 

Writes an End Of File mark on direct_file. 

{ DIZWEOF Writes an End of File mark on direct file. } 
PROCEDURE [XREF] di#weof (direct_file: file); 

2.2.3.3 F#MARK - Check Structure Mark on File 

Returns the "file structure mark" last encountered on any_file. 
{ FZMARK Returns the file structure mark last encountered on file. } 



PROCEDURE [XREF] f#mark (any_file: file; 
VAR mark: file mark); 



o 
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2.2.3.4 F#WORDS - Last Transfer Length on File 



Returns the length of the last transfer from any_file. 



{ FZWORDS Returns length of last transfer to/from file. } 

PROCEDURE [XREF] f#words (any_file: file; 
VAR last transfer length: integer); 
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2.2.4 READING AND WRITING DIRECT FILES 



Transfer of data to and from direct files is performed in groups of 
words (cells). Since the data transfer procedures for direct files (like 
all other programmer defined procedures in CYBIL) must have parameters of 
a specific type, and since we want to be able to transfer items of any 
data type to/from a direct file, the objects of transfer are passed to the 
procedures in two parts : address (usually via the #loc function); and 
length (usually via the //size function). CYBILIO has no way to insure 
that the address and length parameters refer to the same object, therefore 
be warned: "you're on your own" as far as checking parameter correctness 
is concerned. 



v_y 



2.2.4.1 DI#PUT - Sequential Writ e to Direct File 



Writes length__of_source words (cells) from the address specified by 
pointer_to_source to direct_file at its current position. The "random 
file address" of the data written is returned in key. 



{ DIZPUT Writes info from address spec, to direct file's current pos. } 

PROCEDURE [XREF] di#put (direct_f ile: file; 
VAR key: integer; 
pointer_to_source: *cell; 
length of source: integer); 



2.2.4.2 DI#PUTDIR - Random Write to Direct File 



Writes length_of_source words (cells) from the address specified by 
pointer to source to direct file at the "random file address" specified by 
key. 



{ DIZPUTD Writes info to direct file at random address specified. } 

PROCEDURE [XREF] di#putdir (direct_file: file; 
key: integer; 
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pointer_to_source : "cell; 
length of source: integer); 



2.2.4.3 DI//GET - Sequential Read from Direct File 



Reads up to length_of_target words (cells) from direct_file at its 
current position to the address specified by pointer_to__target. The 
"random file address" of the data read is returned in key. Note that an 
"incomplete transfer" can result from this request (see the section on 
"File Structure Creation / Detection" for more information on this 
subject) . 



{ DIZGET Reads info from direct file's current position to add. spec. } 

PROCEDURE [XREF] di#get (direct_f ile: file; 
VAR key: integer; 
pointer_to_target : ~cell; 
length_of_target: integer); 



2.2.4.4 DI#GETDIR - Random Read from Direct File 



Reads up to length_of_target words (cells) from direct_file at the 
"random file address" specified by key to the address specified by 
pointer_to_target. Note that an "incomplete transfer" can result from 
this request (see the section on "File Structure Creation / Detection" for 
more information on this subject). 



{ DIZGETD Reads info from direct file's random file address. } 

PROCEDURE [XREF] di#getdir (direct_f ile: file; 
key: integer; 
pointer_to_target : ~cell; 
length of target: integer); 
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2.2.5 DIRECT FILE STATUS INTERROGATION 



2.2.5.1 DI#LENGTH - Direct File Length? 



Returns the file_length_in_words of direct_file. 



{ DIZLENG Returns length in words of direct file. } 

PROCEDURE [XREF] di#length (direct_f lie: file; 
VAR file length in words: integer); 



2.2.5.2 DI#KEY - Direct File Current Position? 



Returns the current_position_key designating the current position of 
direct_file. 

{ DIZKEY Returns the KEY designating direct file's current position. } 

PROCEDURE [XREF] di#key (direct_f lie: file; 
VAR current position key: integer); 
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2.2.6 EXAMPLES OF DIRECT FILE USAGE 



The examples which follow illustrate the use of direct file procedures. 
The first example creates a "library" of "text modules" from a legible 
file. The modules on the source (legible) file are represented as NOS 
records whose first line contains the module name (and nothing else). The 
second example extracts from the library one of the modules and copies it 
to a file whose name is that of the module. 



2.2.6.1 Create Text Library 



MODULE create_text_library ALIAS 'zpxmcre'; 

{ PXIOTYP Contains CYBIL type declarations. } 

TYPE 

file = "cell, 

file_status = (new#, old#)» 

file_mode = (input//, output//, concurrent//), 

f ile_encoding = (ascii64#, ascii612#, ascii#)» 

file_mark = (data#, eor#, eof#, eoi//), 

f ile_position = (first//, asis//, last//, null//); 

CONST 

return// = last//; 

TYPE 

file_disposition = first// .. return//; 

{ i.e. (first//, asis//, return//) } 

{ LGZOPEN Opens legible file as local file. } 

PROCEDURE [XREF] lg//open (VAR legible_f ile: file; 
file_name: string ( * ); 
status: file_status; 
mode: file_mode; 
position: f ile_position); 

{ LGZCLOS Closes legible file. } 
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PROCEDURE [XREF] lg#close (legible_file: file; 
disposition: f ile_disposition); 

{ LGZGET Reads next complete line from legible file. } 

PROCEDURE [XREF] lg#get (legible_f ile: file; 
VAR number_of_characters_read: integer; 
VAR line: string ( * )); 

{ FZMARK Returns the file structure mark last encountered on file. } 

V J 

PROCEDURE [XREF] f#mark (any_file: file; '— 

VAR mark : f ile_mark) ; 

{ DIZOPEN Opens direct file as local file. } 

PROCEDURE [XREF] di#open (VAR direct_file: file; 
file__name: string ( * ); 
status: file_status; 

mode: file_mode; A 

position: f lle_position); V_y 

{ DIZCLOS Closes direct file. } 

PROCEDURE [XREF] di#close (direct_f ile: file; 
disposition: f ile_disposition); 

{ DIZPUT Writes info from address spec, to direct file's current pos. } 

PROCEDURE [XREF] di#put (direct_f ile: file; v y 

VAR key: integer; 
pointer_to_source: "cell; 
length_of_source: integer); 

{ DIZPUTD Writes info to direct file at random address specified. } 

PROCEDURE [XREF] di#putdir (direct_f ile: file; 
key: integer; 
pointer__to_source : "cell; 
length_of_source: integer); 

{ BIZOPEN Opens binary file as local file. } 

PROCEDURE [XREF] bi#open (VAR binary_file: file; 

file_name: string ( * ); <f~\ 

status: file_status; IS 
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mode: file_mode; 
position: f ile_position) ; 

{ BIZCLOS Closes binary file. } 

PROCEDURE [XREF] bi#close (binary_f ile : file; 
disposition: f ile_disposition); 

{ BIZPUT Writes specified information to binary file. } 

PROCEDURE [XREF] bl#put (binary_file: file; 
pointer_to_source: "cell; 
length_of_source: integer); 

{ BIZGET Reads info from binary file to address specified. } 

PROCEDURE [XREF] bi#get (binary_file: file; 
pointer__to_target : "cell; 
length_of_target : integer); 



TYPE 

directory_descriptor = RECORD 

key : INTEGER, 

length : INTEGER, 
RECEND, 
directory_entry - RECORD 

name : STRING (7), 

length : INTEGER, 

key : INTEGER, 
RECEND; 

CONST 

source_name = 'SOURCE', 
libjiame = 'LIBRARY', 
dir name = 'SCRATCH'; 



PROGRAM create ALIAS 'zpxpcre'; 

VAR 

source : file, 

library : file, 

dir_file : file, 

directory : directory_descriptor , 

current_module : directory_entry, 

line : STRING (256), 
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line_length : INTEGER, 
module_index : INTEGER, 
firstjcey : INTEGER, 
dummy_key : INTEGER, 
mark : file_mark; 

lg#open (source, sour ce_name , old#, input#, first#)> 

bi#open (dir_file, dir_name, new#, output#, first#); 

di#open (library, libjaame, new#, output#, first#); 

directory. length := 0; 

di#put (library, first_key, ^~^ 

#LOC( directory), #SIZE(directory)); , J 

\ y 

/ copy_module_loop/ 
WHILE TRUE DO 

lg#get (source, line_length, line); 
f#mark (source, mark); 
CASE mark OF 
=eoi#= 

EXIT /copy_module_loop/; 
=eof#, eor#= 

CYCLE /copy_module_loop/; v„y 

=data#= 

directory. length := directory. length + 1; 
cur rent_module. name := line(l, line_length); 
current_module. length := 1; 
di#put (library, current_module.key, 
#LOC(current_module.name) , 
#SIZE(current_module.name)); 
/copy_text_loop/ — . 

WHILE TRUE DO v y 

lg#get (source, line_length, line); 
f#mark (source, mark); 
IF mark <> data# THEN 

EXIT /copy_text_loop/; 
IFEND; 

cur rent_module. length := cur r en t_module. length + 1; 
di#put (library, dummy_key, 

#LOC(line_length), #SIZE(line_length)); 
di#put (library, dummy_key, 

#L0C(line), #SIZE(line(l, line_length) )); 
WHILEND /copy_text loop/; 
bi#put (dir_file, ¥LOC(current_module) , 

#SIZE(current_module)); 
CASEND; 
WHILEND /copy_module_loop/ ; *— -^ 

lg#close (source, first#); I | 
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IF directory. length > THEN 
bi#close (dir_file, asis#); 

bi#open (dir_file, dir_name, old#, input* , first#); 
bi#get (dir_file, #LOC(current_module) , 

#SIZE(current_module)); 
di#put (library, directory .key, 

#LOC(current_module) , #SIZE(current_module) ) ; 
FOR module_index := 2 TO directory. length DO 
bi#get (dir_file, #LOC(current_module) , 

#SIZE(current_module)); 
di#put (library, dummy_key, 

#LOC(current_module) , #SIZE(current_module) ) ; 
FOREND; 
di#putdir (library, first_key, 

//LOC(directory) , #SIZE(directory) ); 
I FEND; 

bi#close (dir_file, return#); 
di#close (library, first#); 

PROCEND create; 

MODEND create_text_library; 
2.2.6.2 Extract from Text Library 



MODULE extract_from_text_library ALIAS 'zpxmefl'; 



{ PXIOTYP Contains CYBIL type declarations. } 

TYPE 

file = "cell, 

file_status = (new#, old#), 

file_mode = (input#, output#, concxnrrent// ) , 

f ile_encoding = (ascii64#, ascii612#, ascii#), 

file_mark = (data#, eor#, eof#, eoi#), 

file_position = (first//, asis#, last#, null#); 

CONST 

return# = last#; 

TYPE 

file disposition = first# .. return#; 
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{ i.e. (first*, asis#, return*) } 

{ DIZOPEN Opens direct file as local file. } 

PROCEDURE [XREF] di#open (VAR direct_file: file; 
file_name: string ( * ); 
status: file_status; 
mode: file__mode; 
position: f ile_position); 

{ DIZCLOS Closes direct file. } V J 

PROCEDURE [XREF] di#close (direct_f ile: file; 
disposition: f ile_disposition); 

{ DIZLOCA Positions direct file at location specified. } 

PROCEDURE [XREF] di#locate (direct_f ile: file; 

key: integer); _ 

{ DIZGETD Reads info from direct file's random file address. } 'v_.y 

PROCEDURE [XREF] di#getdir (direct_f ile: file; 
key: integer; 
pointer_to_target : "cell; 
length_of_target: integer); 

{ DIZGET Reads info from direct file's current position to add. spec. } 

PROCEDURE [XREF] di#get (direct_f ile: file; v _, 

VAR key: integer; 
pointer_to_target : "cell; 
length_of_target : integer) ; 

{ LGZOPEN Opens legible file as local file. } 

PROCEDURE [XREF] lg#open (VAR legible_f ile: file; 
file_name: string ( * ); 
status: file_status; 
mode: filejmode; 
position: f ile_position); 

{ LGZCLOS Closes legible file. } 

PROCEDURE [XREF] lg#close (legible_f ile: file; jr- , 

disposition: f ile_disposition); \^J 
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{ LGZPUT Writes source string as complete line to legible file. } 



PROCEDURE [XREF] lg#put (legible_f ile: file; 
line: string ( * )); 



TYPE 

directory_descriptor = RECORD 

key : INTEGER, 

length : INTEGER, 
RECEND, 
directory_entry = RECORD 

name : STRING (7), 

length : INTEGER, 

key : INTEGER, 
RECEND; 

CONST 

lib_name - 'LIBRARY'; 

CONST 
name of module ■ 'TEXTMOD'; 



PROGRAM extract ALIAS 'zpxpefl'; 

VAR 

library : file, 
out_file : file, 

directory : directory_descriptor, 
current_module : directory_entry, 
line : STRING (256), 
line_length : INTEGER, 
module_index : INTEGER, 
dummy_key : INTEGER; 

di//open (library, lib_name, old#, input//, first//); 
di#get (library, dummy_key, 

#LOC( directory), //SIZE(directory) ); 
IF directory. length = THEN 

{ ERROR - module not found } 

RETURN; 
IFEND; 

di//locate (library, directory .key); 
/search_directory/ 
BEGIN 



60460300 02 



2-24 

CYBER IMPLEMENTATION LANGUAGE 

06/22/84 

CYBIL I/O Reference Manual REV: 2 

2.0 I/O PROCEDURES 

2.2.6.2 Extract from Text Library 



o 



FOR module_index := 1 TO directory. length DO 
di#get (library, dummy_key, 

#LOC(current_module) , #SIZE(current_module) ) ; 
IF current._module.name = name_of_module THEN 

EXIT /search_directory/; 
IFEND; 
FOREND; 

{ ERROR - module not found } 
RETURN; 
END /search_directory/; 

lg#open (out_file, name_of_module, new#, output#, first#); 
di#getdir (library, current_module.key, 

#LOC(current_module.name) , v ^ 

#SIZE(current_module.name) ) ; 
lg#put (out_file, current_module.name); 
WHILE current_module. length > 1 DO 
di#get (library, dummy_key, 

#LOC(line_length) , #SIZE(line_length)); 
di#get (library, dummy_key, 

#L0C(line), #SIZE(line(l, line_length))); 
lg#put (out_file, line(l, lineJLength)); ^ 

curr en t_module. length := current_module. length - 1; \.y 

WHILEND; 

di#close (library, first//); 
lg#close (out_file, first#); 

PROCEND extract; 

MODEND extract_from_text_library; 

y" '"•■-. 
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2.3 LEGIBLE FILES 

2.3.1 OPENING AND CLOSING LEGIBLE FILES 

2.3.1.1 LG//OPEN - Open Legible File 

Opens legible_file as local file_name. 

{ LGZOPEN Opens legible file as local file. } 

PROCEDURE [XREF] lg#open (VAR legible_file: file; 
file_name: string ( * ); 
status: file_status; 
mode: file_mode; 
position: file_position); 

2.3.1.2 FffSABF - Setup File for Automatic Buffer Flushing 



Sets up any_file so that its CIO buffer will automatically be flushed 
(if necessary) whenever the program is rolled out. This facility is 
useful when a program issues prompts to a terminal user and then requests 
input, since normally to insure the prompt reaches the user before the 
input request, the program would write an End Of Record (causing the 
buffer to be flushed). On NOS this mechanism is described in the NOS 
Reference Manual in the section on "Program Writing Techniques". 

{ FZSABF Sets up file for automatic buffer flushing. } 
PROCEDURE [XREF] f#sabf (any file: file); 
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2.3.1.3 LG#CODESET - Set Legible File Character Set 



Sets the external character set for legible_file to codeset (default, 
on open, is ascii612# on NOS and is ascii# on NOS/BE). 

{ LGZCODE Sets external character set for legible file. } 



PROCEDURE [XREF] lg#codeset (legible_f lie: file; 
codeset: file encoding); 



2.3.1.4 LG#CL0SE - Close Legible File 



Closes legible file. 



{ LGZCLOS Closes legible file. } 



PROCEDURE [XREF] lg#close (legible_file : file; 
disposition: file disposition); 
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2.3.2 POSITIONING LEGIBLE FILES 

2.3.2.1 LGffFIRST - Position Legible File at BOI 

Positions legible_file at its beginning of information. 

{ LGZFIRS Positions legible file at its Beginning Of Information. } 

PROCEDURE [XREF] lg#first (legible_f ile: file); 

2.3.2.2 LG//LAST - Position Legible File at EOI 

Positions legible_file at its end of information. 

{ LGZLAST Positions legible file at its End Of Information. } 
PROCEDURE [XREF] lg#last (legible_f ile: file); 

2.3.2.3 LG#TAB - Position Legible File at Column 



If column_number is less than or equal to legible_file's current column 
or if it is greater than 256, this procedure does nothing. Otherwise, 
sufficient space characters are written to legible_file so that the next 
(partial) write to legible_file will begin at the specified column_number . 

{ LGZTAB Positions column of next partial write to legible file. } 

PROCEDURE [XREF] lg#tab (legible_f ile: file; 
column number: integer); 
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2.3.3 LEGIBLE FILE STRUCTURE CREATION / DETECTION 

2.3.3.1 LGy/WEOR - Write End Of Record on Legible File 

Writes an End Of Record mark on legible_file. 

{ LGZWEOR Writes an End Of Record mark on legible file. } 
PROCEDURE [XREF] lg#weor (legible_f ile: file); 

2.3.3.2 LG//WEOF - Write End Of File on Legible File 

Writes an End Of File mark on legible_f ile. 

{ LGZWEOF Writes an End Of File mark on legible file. } 
PROCEDURE [XREF] lg#weof (legible_f ile: file); 

2.3.3.3 F//MARK - Check Structure Mark on File 

Returns the "file structure mark" last encountered on any_file. 

{ FZMARK Returns the file structure mark last encountered on file. } 

PROCEDURE [XREF] f#mark (any_file: file; 
VAR mark: file mark); 
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2.3.3.4 FffWORDS - Last Transfer Length on File 



Returns the last_transfer_length of the last transfer to/from any_file. 



{ FZWORDS Returns length of last transfer to/from file. } 

PROCEDURE [XREF] f#words (any_file: file; 
VAR last transfer length: integer); 
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2.3.4 READING AND WRITING LEGIBLE FILES 

Data is transferred to and from legible files in terms of lines or 
partial lines. Internally these (partial) lines are represented by CYBIL 
strings of characters. Externally (on the file) lines are represented in 
6-bit display code, NOS 6/12-bit ASCII, or "8 out of 12 bit" ASCII. Thus, 
data transfers involving legible files imply a translation between these 
character sets (unlike binary and direct file transfers in which the data 
are not modified) . 

Note : that when reading from a legible file assigned to an interactive y j 

terminal, the only file mark possible is data// . Any eor# or eof# marks 
returned to CYBILIO by the operating system after a read from a "terminal 
file" are discarded by CYBILIO (eoi# is never possible from a terminal). 
A line (entered at a terminal) containing zero characters (i.e., the 
carriage return key was "hit" in the first position of the line) is 
returned to the CYBILIO user as an empty line. 



2.3.4.1 LG#PUT - Write Line to Legible File 



Writes the line string as a complete line to legible_f ile. If the last 
write to legible_file was a partial line, that line is first completed, 
and then the line is written. 



{ LGZPUT Writes source string as complete line to legible file. } 

PROCEDURE [XREF] lg#put (legible_f ile: file; 
line: string ( * )); 



2.3.4.2 LG#PUTPART - Write Partial Line to Legible File 



Writes the partial_line string to legible_file. If last_part_of_line 
is TRUE, then the line is completed after partial_line is written by 
writing an End Of Line to legible_file. 

{ LGZPUTP Writes source string as partial line to legible file. } 
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PROCEDURE [XREF] lg#putpart (legible_f ile: file; 
last_part_of_line: boolean; 
partial_line: string ( * )); 



2.3.4.3 LGffWEOL - Write End Of Line on Legible File 



Writes an End Of Line to legible_f ile. If the last write to 
legible_file was partial, that line is completed; otherwise an empty line 
results. 

{ LGZWEOL Writes an End Of Line to legible file. } 
PROCEDURE [XREF] lg#weol (legible_f ile: file); 



2.3.4.4 LG#GET - Read Line from Legible File 



Reads the next complete line from legible_file into line. The actual 
number of characters transferred to line is returned in 
number_of_characters_read. If the previous transfer was partial, a skip 
to the end of that line is performed prior to the transfer to line being 
done. If the line from legible_file is too long to fit into line, the 
line is truncated by skipping to the end of the line after the transfer is 
complete. 



{ LGZGET Reads next complete line from legible file. } 

PROCEDURE [XREF] lg#get (legible_f ile: file; 
VAR number_of_characters_read: integer; 
VAR line: string ( * )); 
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2.3.4.5 LG#GETPART - Read Partial Line from Legible File 



Reads the next partial line from legible_file into partial_line. 
last_part_of_line will be set to TRUE if the end of the line was 
encountered, and set to FALSE otherwise. The actual number of characters 
transferred will be returned in number_of_characters_read. 

{ LGZGETP Reads next partial line from legible file. } ,~^ 

PROCEDURE [XREF] lg#getpart (legible_file: file; v y 

VAR last_part_of_line: boolean; 
VAR number_of_characters_read : integer; 
VAR part ial_line: string ( * )); 
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2.3.5 LEGIBLE FILE STATUS INTERROGATION 
2.3.5.1 F#TERMINAL - File is a Terminal? 



Returns in f ile_is_a_terminal TRUE if any_file is connected to a 
terminal, and FALSE otherwise. 

i { FZTERMI Returns boolean if file is connected to a terminal. } 

PROCEDURE [XREF] f //terminal (any_file: file; 
VAR file is a terminal: boolean); 



2.3.5.2 LG»OLDCODESET - Legible File Character Set? 



Returns the designator for the external character set associated with 
legible_file. 

{ LGZOLDC Returns designator for ext. char, set of legible file. } 

PROCEDURE [XREF] lg#oldcodeset (legible_file: file; 
VAR codeset: file encoding); 



2.3.5.3 LG#C0LN0 - Legible File Column Number? 



Returns the number of the column within the current line of 
legible_file that was last transferred to/from legible_file. Put another 
way, column_number is set to the number of characters so far transferred 
to/from the current line of legible_file. 

{ LGZCOLN Returns col. no. in line of legible file last transferred. } 



O PROCEDURE [XREF] lg#colno (legible_f ile: file; 

VAR column_number : integer); 

o 
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2.3.6 EXAMPLE - COPY COLUMN RANGE OF LEGIBLE FILE 

The following example Illustrates the use of legible file procedures to 
copy one legible file to another. Only data between selected columns on 
the old file is written to the new file, and within those columns, 
trailing space characters are deleted. 



MODULE truncate ALIAS 'zpxmtru'; 

{ PXIOTYP Contains CYBIL type declarations. } 

TYPE 

file = "cell, 

file_status = (new#, old#), 

file_mode = (input//, output//, concurrent//), 

f ile_encoding = (ascii64#, ascii612#, ascii//), 

filejmark = (data//, eor//, eof//, eoi//), 

file_position = (first//, asis#, last//, null//); 

CONST 
return// = last//; 

TYPE 

f ile_disposition = first// . . return//; 

{ i.e. (first//, asis//, return//) } 

{ LGZOPEN Opens legible file as local file. } 

PROCEDURE [XREF] lg//open (VAR legible_f ile: file; 
file_name: string ( * ); 
s tatus : f ile_status ; 
mode: file_mode; 
position: f ile_position); 

{ LGZCLOS Closes legible file. } 

PROCEDURE [XREF] lg//close (legible_f ile: file; 
disposition: f ile_disposition); 

{ LGZGET Reads next complete line from legible file. } 
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PROCEDURE [XREF] lg#get (legible_f ile: file; 
VAR number_of_characters_read: integer; 
VAR line: string ( * )); 

{ LGZPUT Writes source string as complete line to legible file. } 

PROCEDURE [XREF] lg#put (legible_f ile: file; 
line: string ( * )); 

{ LGZWEOL Writes an End Of Line to legible file. } 

PROCEDURE [XREF] lg#weol (legible_f ile: file); 
{ LGZWEOR Writes an End Of Record mark on legible file. } 

PROCEDURE [XREF] lg#weor (legible_f ile: file); 
{ LGZWEOF Writes an End Of File mark on legible file. } 

PROCEDURE [XREF] lg#weof (legible_file: file); 

{ FZMARK Returns the file structure mark last encountered on file. } 

PROCEDURE [XREF] f#mark (any_file: file; 
VAR mark: f ile_mark); 

PROGRAM truncate ALIAS 'zpxptru'; 

CONST 

in_name = 'OLD' , 
out_name = 'NEW' , 
leftmost_column_# =11, 
rightmost_column_# = 72; 

VAR 

in_file : file, 
out_file : file, 
line_ptr : "STRING (*), 
line_length : INTEGER, 
mark : file_mark; 

ALLOCATE line_ptr : [rightmost_column_#] ; 
lg#open (in_file, in_name, old#, input//, first#); 
lg#open (out_file, out_name, new#, output#, first//); 
/main_loop/ 
WHILE TRUE DO 
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lg#get (in_file, line_length, line_ptr~); 
f#mark (in_file, mark); 
CASE mark OF 
=eoi#= 

EXIT /main_loop/ ; 
=eof#= 

lg#weof (out_file); 
=eor#= 

lg#weor (out_file); 
=data#= 

WHILE (line_length > lef tmost_column_#) AND ^-n 

(line_ptr~(line_length) - ' ') DO y j 

line_length := line_length - 1; 
WHILEND; 

line_length := line_length - leftmost_column_# + 1; 
IF line_length > THEN 

lg#put (out_file, line_ptr~(leftmost_column_#, 

line_length) ) ; 
ELSE 

lg#weol (out_file); _ 

IFEND; 
CASEND; v 

WHILEND /main_loop/; 
lg#close (in_file, first//); 
lg#close (out_file, first*); 
FREE Iine_ptr; 

PROCEND truncate; 

MODEND truncate; " 
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2.4 PRINT FILES 

2.4.1 OPENING AND CLOSING PRINT FILES 

2.4.1.1 PR//OPEN - Open Print File 



Opens print_file as local file_name (note the lack of a file_mode 
parameter for this procedure, since print files can only be written). 

{ PRZOPEN Opens print file as local file. } 

PROCEDURE [XREF] pr#open (VAR print_file: file; 
file_name: string ( * ); 
status: file_status; 
position: file position); 



2.4.1.2 PR//PG0V - Define Page Overflow Procedure 



Associates with print_file, the procedure designated by 

page_overflow_proc which will be called whenever the page size of 
print_file is exceeded. Page size is set by PR#LIMIT, default is 60 
lines. The procedure designated by page_overflow_proc should not be 
called directly by the user. If the user wishes to explicitly advance to 
the next page, a call to the pr//page procedure should be used. 

If there is no user supplied page overflow procedure for a print file, 
then CYBILIO simply performs a page eject for the file when the page 
overflow condition occurs. If NIL is specified for page overflow proc, 
any user supplied page overflow procedure currently associated with the 
file is disassociated from the file. 



{ PRZPGOV Calls procedure needed to advance file to next page. } 

PROCEDURE [XREF] pr#pgov (print_file: file; 

page_overflow_proc: "procedure (print_file: file; 
next page #: integer)); 
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2.4.1.3 PR#CODESET - Set Print File Character Set 



Sets the external character set for print_file to codeset (default, on 
open, is ascii612# on NOS and is ascii# on NOS/BE). 



O 



{ PRZCODE Sets ext. char, set for print file. } 

PROCEDURE [XREF] pr#codeset (print_file: file; 
codeset: file encoding); 



2.4.1.4 PR#LIMIT - Set Print File Page Size 



Sets the page size (line limit) for print_file to lines_per_page 
(default, on open, is 60). 

{ PRZLIMI Sets page size (line limit) for print file. } 

PROCEDURE [XREF] pr#limit (print_file: file; 
lines per page: integer); 



2.4.1.5 PR#SETPGN0 - Set Print File Page Number 



Sets the current page number for print_file to current_page_number 
(default, on open, is 0). 



{ PRZSETP Sets current page number for print file. } 

PROCEDURE [XREF] pr#setpgno (print_file: file; 
current page number: integer); 
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2.4.1.6 PR#CLOSE - Close Print File 



Closes print file. 



{ PRZCLOS Closes print file. } 

PROCEDURE [XREF] pr#close (print_file: file; 
disposition: f ile_disposition); 
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2.4.2 POSITIONING PRINT FILES 

2.4.2.1 PR//FIRST - Position Print File at BOI 

Positions print_file at its beginning of information. 

{ PRZFIRS Positions print file at its Beginning Of Information. } 
PROCEDURE [XREF] pr#first (print_file: file); 

2.4.2.2 PR//LAST - Position Print File at EOI 

Positions print_file at its end of information. 

{ PRZLAST Positions print file at its End Of Information. } 
PROCEDURE [XREF] pr#last (print_file: file); 

2.4.2.3 PR#TAB - Position Print File at Column 



If column_number is less than or equal to print_file's current column 
or if it is greater than 136, this procedure does nothing. Otherwise, 
sufficient space characters are written to prlnt_file so that the next 
(partial) write to print_flle will begin at the specified column_number . 

{ PRZTAB Positions print file at column for next partial write. } 

PROCEDURE [XREF] pr#tab (print_file: file; 
column number : integer); 
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2.4.2.4 PR#LINE - Position Print File at Line 



Positions print_file at the specified linejiumber. This will be on the 

current page if line_number is greater than the current line number and 

less than or equal to page size; or on the next page (after invoking the 

page overflow mechanism) if line_number is less than or equal to the 

current line number. If line_number is greater than the page size, the 
file will be positioned at the top of the next page. 



{ PRZLINE Positions print file at specified line. } 

PROCEDURE [XREF] pr#line (print_file: file; 
line number: integer); 



2.4.2.5 PR#SKIP - Skip Lines on Print File 



If number_of_lines = -1, the next line written to print_file will 
overprint the current line. If number_of_lines + print_f lie's current 
line number is greater than the page size, the page overflow mechanism is 
invoked. Otherwise, number_of_lines empty lines will be written to 
print file. 



{ PRZSKIP Skips lines on print file from current position. } 

PROCEDURE [XREF] pr#skip (print_file: file; 
number of lines : integer) ; 



2.4.2.6 PR#EJECT - Position Print File at Top of Page 



Positions print_file at the first line (top) of the next page. This 

procedure should only be called by the routine that processes page 

overflow conditions: pr#pgov (see the section on "Print Files" under "File 
Types"). 
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{ PRZEJEC Positions print file to first line (top) of next page. } 
PROCEDURE [XREF] pr#eject (print_file: file); 

2.4.2.7 PR#PAGE - Start New Page on Print File 



Increments print_f lie's page number and calls the routine that 
processes page overflow conditions: prZ/pgov (see the section on "Print 
Files" under "File Types"). 

{ PRZPAGE Increments print file's page number. } 
PROCEDURE [XREF] pr#page (print file: file); 
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2.4.3 PRINT FILE STRUCTURE CREATION 

2.4.3.1 PR#WEOR - Write End Of Record on Print File 

Writes an End Of Record mark on print_file. 

{ PRZWEOR Writes an End Of Record mark on print file. } 
PROCEDURE [XREF] pr#weor (print_file: file); 

2.4.3.2 PR//WEOF - Write End Of File on Print File 

Writes an End Of File mark on print_file. 

{ PRZWEOF Writes an End Of File mark on print file. } 
PROCEDURE [XREF] pr#weof (print file: file); 
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2.4.4 WRITING PRINT FILES 



Print files are a special form of legible files used only for output. 
In addition to the (partial) line writes similar to those for legible 
files, print files also have "format" control procedures to handle page 
overflow processing and vertical spacing and tabbing (see the section on 
"Positioning Print Files" for more information) . 



2.4.4.1 PR#PUT - Write Line to Print File 



Writes the line string as a complete line to print_file. If the last 
write to print_file was a partial line, that line is first completed, and 
then the line for line is written. 



{ PRZPUT Writes source string as a complete line to print file. } 

PROCEDURE [XREF] pr#put (print_file: file; 
line: string ( * )); 



2.4.4.2 PR#PUTPART - Write Partial Line to Print File 



Writes the partial_line string to print_file. If last_part_of_line is 
TRUE, then the line is completed after partial_line is written by writing 
an End Of Line to print_file. 

{ PRZPUTP Writes source string as a partial line to print file. } 

PROCEDURE [XREF] pr#putpart (print_file: file; 

last_part_of_line: boolean; -- 

partial_line: string ( * )); 
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2.4.4.3 PR//WE0L - Write End Of Line on Print File 



Writes an End Of Line to print_file. If the last write to print_file 
was partial, that line is completed; otherwise an empty line results. 

{ PRZWEOL Writes an End Of Line to print file. } 
PROCEDURE [XREF] pr#weol (print file: file); 
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2.4.5 PRINT FILE STATUS INTERROGATION 

2.4.5.1 PR#OLDCODESET - Print File Character Set? 



Returns the designator for the external character set associated with 
print_file. 

{ PRZOLDC Returns designator for ext. char, set of print file. } 



PROCEDURE [XREF] pr#oldcodeset (print_file: file; 
VAR codeset: f ile_encoding); 



2.4.5.2 PR#COLNO - Print File Column Number^ 



Returns the number of the column within the current line of print_file 
that was last transferred to/from print_file. Put another way, 
column number is set to the number of characters so far transferred 
to/from the current line of print_file. 

{ PRZCOLN Returns current line col. no. of print file last transferred. } 

PROCEDURE [XREF] pr#colno (print_file: file; 
VAR columnjaumber : integer); 



2.4.5.3 PRflLINO - Print File Line Number? 

Returns the number of the current line within the current page of 
print file. After any repositioning command (skip, eject, 
set line_number) the line number returned is the next line to be printed. 
After a print command Tput, putpart, weol) , the linejtiumber is the line 
just printed. 

Before doing any I/O, the line number is 500. 
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{ PRZLINO Returns no. of lines within current page of print file. } 

PROCEDURE [XREF] pr#lino (print_file: file; 
VAR line number: integer); 



2.4.5.4 PR//PGN0 - Print File Page Number? 



Returns the number of the current page for print file. 



{ PRZPGNO Returns number of current page for print file. } 



PROCEDURE [XREF] pr#pgno (print_file: file; 
VAR page_number : integer); 



2.4.5.5 PR//0LDLIMIT - Print File Page Size? 



Returns print file's page size (line limit). 



{ PRZOLDL Returns print file's page size (line limit). } 

PROCEDURE [XREF] pr#oldlimit (print_file: file; 
VAR lines per page: integer); 
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2.4.6 EXAMPLE - LIST LEGIBLE FILE 

The following example illustrates the use of print file procedures (and 
legible file procedures). Note particularly the page overflow processing 
procedure. 



MODULE list ALIAS 'zpxmlis'; 

{ PXIOTYP Contains CYBIL type declarations. } 

TYPE 

file = "cell, 

file_status = (new//, old//), 

file_mode = (input//, output//, concurrent//), 

file_encoding = (ascii64#, ascii612#, ascii//), 

filejmark = (data//, eor#, eof#, eoi#), 

file_position = (first//, asis//, last#, null//); 

CONST 

return// = last//; 

TYPE 

f ile_disposition = first// .. return//; 

{ i.e. (first//, asis//, return//) } 

{ LGZOPEN Opens legible file as local file. } 



PROCEDURE [XREF] lg#open (VAR legible_f ile : file; 
file_name: string ( * ); 
status: file_status; 
mode : f ile_mode ; 
position: f ile_position); 

{ LGZCLOS Closes legible file. } 

PROCEDURE [XREF] lg#close (legible_f ile: file; 
disposition: f ile_disposition); 



x_.^ 



{ LGZGETP Reads next partial line from legible file. } 

PROCEDURE [XREF] lg#getpart (legible_f ile: file; I | 
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2.4.6 EXAMPLE - LIST LEGIBLE FILE 



VAR last_part_of_line: boolean; 

VAR number_of_characters_read: integer; 

VAR partial_line: string ( * )); 

{ FZMARK Returns the file structure mark last encountered on file. } 

PROCEDURE [XREF] f#mark (any_file: file; 
VAR mark: file_mark); 

{ PRZOPEN Opens print file as local file. } 

PROCEDURE [XREF] pr#open (VAR print_file: file; 
file_name: string ( * ); 
status: file_status; 
position: file_position); 

{ PRZPGOV Calls procedure needed to advance file to next page. } 

PROCEDURE [XREF] pr#pgov (print_file: file; 

page_overflow_proc: "procedure (print_file: file; 
next_page_#: integer)); 

{ PRZCLOS Closes print file. } 

PROCEDURE [XREF] pr#close (print_file: file; 
disposition: f ile_disposition); 

{ PRZEJEC Positions print file to first line (top) of next page. } 

PROCEDURE [XREF] pr#eject (print_file: file); 

{ PRZSKIP Skips lines on print file from current position. } 

PROCEDURE [XREF] pr#skip (print_file: file; 
number_of_lines : integer ) ; 

{ PRZLINE Positions print file at specified line. } 

PROCEDURE [XREF] proline (print_file: file; 
1 ine_number : integer ) ; 

{ PRZLIMI Sets page size (line limit) for print file. } 

PROCEDURE [XREF] pr#limit (print_file: file; 
lines_per_page: integer); 

{ PRZOLDL Returns print file's page size (line limit). } 
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PROCEDURE [XREF] pr#oldlimit (print_file: file; 
VAR llnes_per_page: Integer); 

{ PRZPGNO Returns number of current page for print file. } 

PROCEDURE [XREF] pr#pgno (print_file: file; 
VAR page_number : integer); 

{ PRZTAB Positions print file at column for next partial write. } 

PROCEDURE [XREF] pr#tab (print_file: file; 
c olumn_number : integer ) ; 

{ PRZPUTP Writes source string as a partial line to print file. } 

PROCEDURE [XREF] pr#putpart (print_file: file; 
last_part_of_line: boolean; 
partial_line: string ( * )); 

{ PRZWEOL Writes an End Of Line to print file. } 

PROCEDURE [XREF] pr#weol (print file: file); 



CONST 

in_name = 'LEGFILE'; 

VAR 

file_# : INTEGER := 1, 
record # : INTEGER :- 1; 



PROCEDURE page_overflow_handler 
( f : file; 

next_page_# : INTEGER); 

VAR 

conv_holder : STRING (10), 
conv_length : INTEGER, 
old_page_size : INTEGER; 

IF next_page_# > 1 THEN 

pr#oldlimit (f, old_page_size) ; 
pr#limit (f , old_page_size +2); 
pr#line (f , old_page_size + 2); 
pr#tab (f, 70); 
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2.4.6 EXAMPLE - LIST LEGIBLE FILE 



pr#putpart (f, FALSE, 'PAGE '); 

STRINGREP (conv_holder, conv_length, next_page_# - 1); 

pr#putpart (f, TRUE, conv_holder(l, conv_length) ); 

pr#limit (f, old_page_size) ; 
IFEND; 

pr#eject (f); 

pr#putpart (f , FALSE, 'LISTING OF '); 
pr#putpart (f, FALSE, injiame); 
pr#tab (f, 50); 

pr#putpart (f, FALSE, 'FILE '); 
STRINGREP (conv_holder, conv_length, file_#); 
pr//putpart (f, FALSE, conv_holder(l, conv_length)); 
pr#putpart (f, FALSE, ', RECORD '); 
STRINGREP (conv_holder, cony_length, record_#); 
pr#putpart (f, TRUE, conv_holder(l, conv length)); 
pr#skip (f, 2); 



PROCEND page overflow handler; 



PROGRAM list ALIAS 'zpxplis'; 

CONST 

out_name = 'OUTPUT'; 

VAR 

in_file : file, 
out_file : file, 
original_page_size : INTEGER, 
page_# : INTEGER, 
line : STRING (80), 
line_length : INTEGER, 
eol : BOOLEAN, 
mark : file_mark; 

lg//open (in_file, in_name, old//, input//, first//); 
pr#open (out_file, out_name, new#, asis#); 
pr#pgov (out_file, *page_overflow_handler); 
pr# old limit (out_file, original_page_size); 
pr//limit (out_file, original_page_size - 2); 
/main_loop/ 
WHILE TRUE DO 

lg#getpart (in_file, eol, line_length, line); 

f//mark (in_file, mark); 

CASE mark OF 

=eoi#= 

pr#limit (out file, original page size); 
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2.4.6 EXAMPLE - LIST LEGIBLE FILE 

pr#line (out_file, original_page_size); 
pr#tab (out_file, 70); 
pr#putpart (out_file, FALSE, 'PAGE '); 
pr#pgno (out_file, page_#); 
STRINGREP (line, line_length, page_#); 
pr#putpart (out file, TRUE, line(l, line_length) ) ; 
EXIT /main_loop7; 
=eof#= 

file_# := file_# +1; 
record_# := 1; 

pr#line (out_file, original_page_size - 2); ^— ^ 

pr#weol (out_file); v J 

=eor#= 

record_# := record_# +1; 

pr#line (out_file, original_page_size - 2); 
pr#weol (out_file); 
=data#= 

IF line_length > THEN 

pr#putpart (out_file, eol, line(l, line_length)); 
ELSE 

pr#weol (out_file); \ 

IFEND; X S 

CASEND; 
WHILEND /main_loop/; 
lg#close (in_file, first#); 
pr //close (out_file, asis#); 

PROCEND list; 

MODEND list; 
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3.0 CYBILIO ERROR MESSAGES 



This section describes the error messages that may be received as a 
result of improper use of CYBILIO. If a condition described by one of 
these messages arises: 

- the I/O error message will be sent to the dayfile 

- the message - INTERNAL ERROR IN prognam will be sent to the dayfile 
(where prognam is the name of the program as extracted from the job 
communication area) 

- the program is aborted. 

In the message prototypes that follow f ilenam will be replaced by the 
name of the file in question when the message appears in the dayfile. The 
reason that some of the messages do not have the file name in them is 
that, in those conditions, the file name is not known. 



-10 ERR- NO MEM TO OPEN FILE f ilenam 

This message means that there was insufficient space to allocate the 
descriptor and/or cio buffer for the file. 



-10 ERR- ILLEGAL FILE NAME 

This message means that an attempt was made to open a file with a name 
that did not consist of from 1 to 7 letters and/or digits. 



-10 ERR- ILLEGAL OPEN REQ f ilenam 

This message means that an invalid combination of parameters was given 
to an open procedure (e.g., "new#, input#" is illegal). 



•10 ERR- FILE NOT OPEN 

This message indicates that an undefined variable of type file was 
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-10 ERR- ILLEGAL SKIP COUNT filenam 

This message indicates that the pr//skip procedure was passed a skip 
count less than -1. 
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passed to a CYBILIO procedure other than one of the open procedures. 



-10 ERR- ILLEGAL INPUT REQ filenam 

This message means that an attempt was made to read from a file that 
was opened only for output . 



-10 ERR- ILLEGAL OUTPUT REQ filenam \^_J 

This message means that an attempt was made to write to a file that was 
opened only for input. 



-10 ERR- KEY BEYOND E-0-I filenam 

This message indicates that an attempt was made to perform a direct 
file operation with a key that was outside the bounds of the file (i.e., 
the key did not specify a "random address" that is in the file) . 



-10 ERR- ILLEGAL LINE NUM filenam 

This message means that the pr#line procedure was passed a line number 
less than 1. 



v ^ 
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